home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 1 / Gold Medal Software Volume 1 (Gold Medal) (1994).iso / graphics / smooth21.arj / SMOOTH.DOC < prev    next >
Text File  |  1993-11-01  |  22KB  |  522 lines
  1.  
  2.  
  3.  
  4.           SMOOTH v2.1 - POV Surface Normal Modeling Program
  5.  
  6.       Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  7.  
  8.  
  9.  
  10.  
  11.                           ---USERS GUIDE---
  12.  
  13.  
  14.  
  15.  
  16.  
  17. ----------------------------------------------------------------------
  18. 1.0   Introduction
  19. ----------------------------------------------------------------------
  20.  
  21. SMOOTH v2.1 is a utility that reads in raw triangle data, and allows
  22. the user to manipulate that data using the various commands available.
  23. The major function of SMOOTH v2.1 is to calculate the surface normals
  24. for each triangle.  This "polygon patch" or "smooth triangle" output
  25. can be used with a raytracing program to produce smooth looking
  26. surfaces, instead of the flat "faceted" look you get with triangles
  27. alone.  Consider the difference between a geodesic dome and a smooth
  28. sphere, and you'll have the idea.  (See SMOOTH.GIF for an example)
  29.  
  30. SMOOTH v2.1 has a variety of special features which can be used with
  31. it's internal scene file generator to create "ready-to-render" POV
  32. files. SMOOTH v2.1 supports POV version 1.0 and 2.0 and can generate
  33. scene files in the new version 2.0 language.  can also create bounding
  34. boxes for the object described by the triangle data set.  Some of the
  35. advanced features include:
  36.  
  37.         - Bounding Boxes.  SMOOTH v2.1 can calculate bounding boxes
  38.           for the triangle data.  Proper use of bounding boxes can
  39.           reduce the rendering time for complex scenes comprised of
  40.           many objects.
  41.  
  42.         - Studio Lighting.  SMOOTH v2.1 allows you to select up to ten
  43.           modeling lights to create lighting for the "ready-to render"
  44.           scenes.
  45.  
  46.         - Field of View Angle.  SMOOTH v2.1 allows you to select the
  47.           Field of View Angle and calculates the new camera position
  48.           automatically.
  49.  
  50.         - Various Output Formats.  SMOOTH v2.1 can output triangle or
  51.           smooth_triangle data for both POV v1.0 and POV v2.0 as well
  52.           as 'raw' format.
  53.  
  54.         - Aspect Ratio.  SMOOTH v2.1 allows the user to enter the
  55.           aspect ratio of their display device to maintain the image
  56.           quality.
  57.  
  58.         - Seperate File Types.  SMOOTH v2.1 can create
  59.           "ready-to-render" scene files with camera and lighting data.
  60.           SMOOTH v2.1 can also create include files which contain only
  61.           the triangle data for inclusion in other POV scenes.
  62.  
  63. All of SMOOTH's options are selected via the command line switches
  64. (See Command Line Options) and control the operation of SMOOTH v2.1.
  65.  
  66. ----------------------------------------------------------------------
  67. 2.0   Input Requirements
  68. ----------------------------------------------------------------------
  69.  
  70. The input data should consist of raw triangle data in groups of 9;
  71. three numbers (x,y,z) per point, and three points per triangle. The
  72. data for each triangle should be included on one line (See example
  73. below). There is an option to quickly scan an input file to see if it
  74. conforms to SMOOTH's input standards (See -c option). You may also
  75. have comments in your raw data file indicated by a line that starts
  76. with a ; character.  These will be ignored by SMOOTH and not passed to
  77. the output.  In future versions these will be used to pass commands to
  78. SMOOTH.
  79.  
  80. Example of SMOOTH input file:
  81.  
  82. ; This is a comment line and will be ignored by SMOOTH.
  83. -1.00 2.00 -3.00 4.00 -5.00 6.00 -7.00 8.00 -9.00
  84. 10.00 11.00 12.00 13.00 14.00 15.00 16.00 17.00 18.00
  85.  
  86. ----------------------------------------------------------------------
  87. 3.0   Command Line Options
  88. ----------------------------------------------------------------------
  89.  
  90. This section describes the command line options and their function. An
  91. option may be given in upper or lower case, and is preceeded with a
  92. dash, forward slash or backslash.  The following is an example of a
  93. SMOOTH v2.1 command line:
  94.  
  95. C>smooth -lstudio.dat -s -p1 -b image.raw myimage
  96.  
  97. This line instructs SMOOTH v2.1 to read the 'raw' triangle data in the
  98. file IMAGE.RAW and create a "ready-to-render" scene in POV v1.0 format
  99. using bounding boxes and the lighting described in the file
  100. STUDIO.DAT.  The scene file is written to the disk as MYIMAGE.POV.
  101. The following describes the function of each of the command line
  102. options.
  103.  
  104. 3.1   -p1|p2 : Output Formats
  105.  
  106. Two output formats are available via a command line switch and are
  107. listed below:
  108.  
  109.         -p1 : POV v1.0
  110.         -p2 : POV v2.0
  111.  
  112. An example of each of these formats is given in the accompanying file
  113. SAMPLE.DOC. If no command line format option is specified, the output
  114. will be in "raw" form; just the triangles and normals without any
  115. other text.
  116.  
  117. 3.2   -c : Check Input File Option
  118.  
  119. Due to the rather strict input requirements (hope to have this fixed
  120. in the next version) the -c command line option will scan the input
  121. file and make sure it conforms to SMOOTH's input requirements. If
  122. SMOOTH cannot read the data file the program will stop and the
  123. offending line number of the file will be indicated. For example,
  124. entering 'SMOOTH -C TEST.DAT' would produce the following results.
  125.  
  126. SMOOTH v2.1 - POV Surface Normal Modeling Program
  127. Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  128.  
  129. Scanning the input file for errors.
  130.  
  131. 123 triangles processed.  File is OK!
  132.  
  133. SMOOTH indicated that it was able to correctly read the file and would
  134. be able to process the triangle data.  Remember that the only text
  135. allowed in the raw triangle data is comments that start with the
  136. character ';'. Any other text will cause truncated or strange results
  137. if processed.
  138.  
  139. 3.3   -x : Surface Normal Output Mode
  140.  
  141. Sometimes it is desirable to simply convert the raw triangle data to
  142. another format without including the surface normals.  Using the -x
  143. command line option will "turn off" the output of the surface normal
  144. data and create regular triangles instead of smooth triangles.
  145.  
  146. Sample output (POV 1.0 format) without -x command line option:
  147.  
  148. //
  149. // Persistance of Vision v1.0 Data File
  150. //
  151. // Created by SMOOTH v2.1 - POV Surface Normal Modeling Program
  152. // Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  153. //
  154.  
  155. smooth_triangle { 
  156. <  0.0000  8.8000  0.0000 > <  0.0000 -28.8767 -0.0000 >
  157. <  6.3900  6.3800  0.0600 > < -24.0002 -19.5635 -3.5556 >
  158. <  4.4800  6.3800  4.5600 > < -14.4201 -19.5469 -19.4753 >
  159.  }
  160.  
  161. With -x command line option:
  162.  
  163. //
  164. // Persistance of Vision v1.0 Data File
  165. //
  166. // Created by SMOOTH v2.1 - POV Surface Normal Modeling Program
  167. // Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  168. //
  169.  
  170. triangle { 
  171. <  0.0000  8.8000  0.0000 > 
  172. <  6.3900  6.3800  0.0600 > 
  173. <  4.4800  6.3800  4.5600 > 
  174.  }
  175.  
  176. 3.4   -b : Bounding Box Output
  177.  
  178. Some raytracers are capable of surrounding a complex object with a
  179. simple shape to reduce the time needed to render the object.  When a
  180. ray is fired at the scene it checks to see if it has intersected the
  181. bounding shape first.  If not, then the complex object can be skipped.
  182. If it does intersect the bounding shape, then the ray is tested
  183. against the complex object in side the box.  Since the time to check
  184. the ray against the simple shape is much less than checking it against
  185. complex objects, a time savings is realized.
  186.  
  187. SMOOTH calculates the coordinates of a box shape that surrounds all
  188. the triangles found in the input file.  Using the -b command line
  189. option allows SMOOTH to include that information in the output file.
  190. Due to the way SMOOTH calculates the bounding box coordinates, you may
  191. have to enlarge the box a little to eliminate any clipping that may
  192. occur.
  193.  
  194. 3.5   -q : Quite Mode Option
  195.  
  196. Normally the program will display a count on the screen as the
  197. triangles are read in.  Using the -q option turns off the count during
  198. processing. This is especially useful if you are redirecting the
  199. screen output of SMOOTH to another device such as a printer or disk
  200. file.
  201.  
  202. 3.6   infile : Input File Option
  203.  
  204. This is the full pathname of the file containing the raw triangle
  205. data.
  206.  
  207. 3.7   outfile[.???] : Output File Option
  208.  
  209. This is the full pathname of the file that will contain the data
  210. generated by SMOOTH.  If you do not supply an extension, SMOOTH will
  211. automatically supply an extension that is appropriate for the output
  212. format that you are using.  For example, a POV v1.0 scene file would
  213. have the extension '.pov', a POV v2.0 include file would have the
  214. extension '.inc' and a 'raw' triangle file would have the extension
  215. '.raw'.
  216.  
  217. 3.8   -?|h : Brief Usage Instructions
  218.  
  219. Using the -? command line option displays a brief help screen.
  220.  
  221. 3.9   -i|s : Output File Type Option
  222.  
  223. This option allows you to specify which type of output file you would
  224. like. The -i option tells SMOOTH v2.1 to create a POV include file.
  225. This file has the object declaration and triangle data.  If selected,
  226. the bounding box data is also included.  This file is designed to be
  227. used as an include file in another POV scene file, therefore no camera
  228. or lighting information is included.  Be aware that SMOOTH v2.1
  229. creates one object that contains a union of all the triangles found in
  230. the input file.  SMOOTH v2.1 declares this object with the name
  231. 'Image'.  You may later edit the file and change this to whatever you
  232. would like.  Include files have the extension '.inc'.
  233.  
  234. The -s option performs the same functions as the -i option, but it
  235. also includes the camera and lighting information allowing the scene
  236. to be rendered immediately without any modifications.  Scene files
  237. have the extension '.pov'.
  238.  
  239. 3.10  -fxxx : Field of View Angle
  240.  
  241. This option allows the user to enter the Field of View Angle.  The
  242. field of view angle is used to calculate the position of the camera
  243. from the center of the object in the scene.  SMOOTH v2.1 uses a method
  244. that will always calculate the camera position to keep the object in
  245. the center of the scene at a predetermined size.  Changing the Field
  246. of View Angle doesn't change the size of the object, but it does
  247. change the distance of the camera from the object.  This can have
  248. different effects on the lighting of the object.  Note that the input
  249. is in degrees, SMOOTH v2.1 calculates the distance parameter required
  250. in the camera definition.
  251.  
  252. 3.11  -axxxx : Aspect Ratio
  253.  
  254. SMOOTH v2.1 allows the user to define the "aspect ratio" (height to
  255. width ratio) of the resulting image.  If you wanted a tall skinny
  256. image or a short wide panoramic image or a perfectly square image then
  257. you should adjust the aspect ratio.
  258.  
  259. Most computer video modes and graphics printers use perfectly square
  260. pixels.  For example Macintosh displays and IBM S-VGA modes 640x480,
  261. 800x600 and 1024x768 all use square pixels.  When your intended
  262. viewing method uses square pixels then the aspect ratio should be set
  263. properly. Note that 640/480=4/3 (or 1.333) so the ratio is proper for
  264. this square pixel mode.
  265.  
  266. 3.12  -o : Object Name
  267.  
  268. SMOOTH v2.1 allows the user to define the name of the object used in
  269. the POV scene file.  If no name is defined, the default name
  270. "Smooth_Object" is used.
  271.  
  272. 3.13  -t : Texture Name
  273.  
  274. SMOOTH v2.1 allows the user to select a texture name for the object in
  275. the scene file.  If no texture is defined the default texture
  276. "Brass_Metal" is used.  Since only one object is created, the texture
  277. name will be used to describe the entire object.
  278.  
  279. 3.14  -l<filename> : Studio Lighting File
  280.  
  281. SMOOTH v2.1 allows the user to select any combination of up to ten
  282. light sources to light the object in the scene.  If no studio file is
  283. used then the default "Camera Flash" lighting is used.  Camera Flash
  284. lighting places one light source slightly above the camera (simulating
  285. the flash on a camera) for lighting the scene.
  286.  
  287. The studio file is a simple ASCII file with ten entries (one for each
  288. light source) that describe the characteristics of the light.  The
  289. first five line entries are for each of the five spotlights and the
  290. second five lines are for each of the five modeling lights.  An
  291. example of a studio file is as follows;
  292.  
  293. White    <--- Turn on Spotlight 1 and make the color White
  294. Gray50   <--- Turn on Spotlight 2 and make the color Gray50
  295. -off     <--- Turn off Spotlight 3
  296. -off     <--- Turn off Spotlight 4
  297. -off     <--- Turn off Spotlight 5
  298. -off     <--- Turn off Modeling Light 1
  299. -off     <--- Turn off Modeling Light 2
  300. -off     <--- Turn off Modeling Light 3
  301. Gray25   <--- Turn on Modeling Light 4 and make the color Gray25
  302. -off     <--- Turn of Modeling Light 5
  303.  
  304. The position of each light is calculated for each scene and will
  305. always appear in the same relative position.  See the diagram below
  306. for the positions of the lighting;
  307.  
  308.          O------------------------------------------------O
  309.          | \__ Model Light 4      |    Model Light 1 ___/ |
  310.          |                        |                       |
  311.          |                        |                       |
  312.   T      |                        |                       |
  313.   H      |    |----> X            |    |----> X           |
  314.   E      |    |                   |    |                  |
  315.          |    |--Spotlight 4 ctr  |    |--Spotlight 1 ctr |
  316.   S      |                        |                       |
  317.   C      |------------------------O-----------------------|
  318.   E      |                        | \__ Model/Spot Light 5|
  319.   N      |                        |                       |
  320.   E      |   Spotlight 3 ctr--|   |   Spotlight 2 ctr--|  |
  321.          |                    |   |                    |  |
  322.          |           X <------|   |           X <------|  |
  323.          |                        |                       |
  324.          |  __ Model Light 3      |     Model Light 2 __  |
  325.          | /                      |                     \ |
  326.          O------------------------------------------------O
  327.  
  328.  
  329. In the diagram above the scene is divided into 4 sections.  The
  330. modeling lights are located in each of the corners with one located in
  331. the center.  The modeling lights are in the same plane (z-axis) as the
  332. camera.  The spotlights are located slightly below the modeling lights
  333. and "point-at" the center of each section, with exception of spotlight
  334. 5 which points at the center of the object.  (See PART.TGA for an
  335. example scene created using the part.raw data and the studio.dat
  336. lighting file.)
  337.  
  338. 3.15  -r : Report File Option
  339.  
  340. Acts the same as the -c command line option, but also creates a report
  341. describing the bounding box size and the camera parameters.  Use this
  342. to check and see if the program will handle the number of triangles in
  343. the input file.
  344.  
  345.  
  346.  
  347. ----------------------------------------------------------------------
  348. 4.0   Memory Considerations
  349. ----------------------------------------------------------------------
  350.  
  351. This information is from the documentation for the original smoothing
  352. routine written by Mike Schoenborn.
  353.  
  354. Sorry, it's impossible to say (simply) exactly how much memory is
  355. required to run this program.  The memory requirements are determined
  356. by the number of triangles and number of points, obviously, but also
  357. by how the triangles are arranged, the number of points which are
  358. unique, which points belong to which triangles...
  359.  
  360. Consider these two figures...
  361.        _______                  _____________________________________
  362.      / \     / \               / \         / \         / \         /
  363.    /    \   /    \           /     \     /     \     /     \     /
  364.  /_______\/________\       /         \ /         \ /         \ /
  365.  \       /\       /       -------------------------------------
  366.    \    /   \    /
  367.      \/_______\/
  368.  
  369. 6 triangles                          6 triangles
  370. 7 unique points                      8 unique points
  371. 6 points belong to only 2 tri's      2 points belong to only 1 tri
  372. 1 point belongs to 6 tri's           2 points belong to 2 tri's
  373.                                      4 points belong to 3 tri's
  374.  
  375. Since the program doesn't know how the input triangles are going to be
  376. arranged, it can't plan ahead of time on how to balance the memory
  377. allocation for the triangles, points, and (most awkwardly) the
  378. "belongs to" information.
  379.  
  380. I've sent a data set of more than 5000 triangles through and the
  381. program had no problem with it.  It will definately handle a lot, but
  382. you just can't be exact as to how much "a lot" actually is.  If it
  383. does run out of memory, it will abort with a message saying how much
  384. it did handle before choking.
  385.  
  386. If you do run out of memory try to split up the data into multiple
  387. groups and process each group seperately.  If you go this route,
  388. consider the layout of your data and keep in mind that the normals are
  389. calculated based on adjoining triangles only. You could split your
  390. data, allowing a 1 triangle overlap at the split, process each group,
  391. then remove the overlap duplicate data when you recombine the outputs.
  392.  
  393. ----------------------------------------------------------------------
  394. 5.0   Error Messages
  395. ----------------------------------------------------------------------
  396.  
  397. Invalid Field of View Angle
  398.         The Field of View Angle given is not within the accepted
  399.         range.  If you specify a Field of View Angle that is less than
  400.         1 degree or more than 179 degrees this error will occur.
  401.  
  402. No Input Filename Found
  403.         SMOOTH could not find the filename of the input file in the
  404.         command line.
  405.  
  406. No Output Filename Found
  407.         SMOOTH could not find the filename of the output file in the
  408.         command line.
  409.  
  410. Too Many Filenames Specified
  411.         SMOOTH found more filenames in the command line than required.
  412.  
  413. ----------------------------------------------------------------------
  414. 6.0   Credit Where Credit is Due!
  415. ----------------------------------------------------------------------
  416.  
  417. The original 'C' source code for the surface normal computations was
  418. taken from the program 'SANDPAPER' written by Mike Schoenborn.
  419.  
  420. ----------------------------------------------------------------------
  421. 7.0   Legal Stuff (and its a shame to have to do this!)
  422. ----------------------------------------------------------------------
  423.  
  424. SMOOTH v2.1 is copyrighted freeware, and as such, may be used and
  425. distributed without charge to the end user.  I still retain all
  426. copyrights to the source code with the exception of the public-domain
  427. code originally written by Mike Schoenborn.
  428.  
  429.                              DISTRIBUTION
  430.  
  431. You may freely distribute SMOOTH v2.1 in its original package as long
  432. as there is no charge for this service.  Distribution centers may
  433. distribute the original SMOOTH v2.1 package on disk as long as their
  434. is a charge of no more than $5.00 US to the end user.
  435.  
  436.                               DISCLAIMER
  437.  
  438. This software is provided as is without any guarantees or warranty.
  439. Although the authors have attempted to find and correct any bugs in
  440. the package, they are not responsible for any damage or losses of any
  441. kind caused by the use or misuse of the package. The authors are under
  442. no obligation to provide service, corrections, or upgrades to this
  443. package.
  444.  
  445. ----------------------------------------------------------------------
  446. 8.0   Contacting the Author
  447. ----------------------------------------------------------------------
  448.  
  449. There is no registration fees or costs associated with SMOOTH.
  450. However, I would like to here from you, if you find SMOOTH of value,
  451. or even if you consider it a waste of disk space, drop me a postcard.
  452. If you would like to send me comments, bug reports, or possible
  453. enhancements to SMOOTH you can write me at the following address:
  454.  
  455.                              Jeff Burton
  456.                          415 Franklin Street
  457.                           Paducah, KY 42003
  458.  
  459. You can also leave a message to JEFF BURTON in the RIME Ray Trace
  460. Forum.
  461.  
  462. Or you can leave a message to JEFF BURTON at the home of SMOOTH, the
  463. Midnight BBS (502) 443-7514 14.4/v.42bis 24hrs.
  464.  
  465. ----------------------------------------------------------------------
  466. 9.0   Revision History
  467. ----------------------------------------------------------------------
  468.  
  469. Changes in SMOOTH v2.1
  470.  
  471. * Added degenrate triangle input detection.
  472.  
  473. * Added the -o object name switch.
  474.  
  475. * Added the -t texture name switch.
  476.  
  477. Changes in SMOOTH v2.0
  478.  
  479. * Added the -l studio file option which lets the user manipulate up to
  480.   ten light sources for the scene.
  481.  
  482. Changes in SMOOTH v1.4
  483.  
  484. * Added the -i|s switch to allow the user to choose the output file
  485.   type.
  486.  
  487. * Added the -c and -r switches to (C)heck the input file and (R)eport
  488.   the parameters of the input file.
  489.  
  490. Changes in SMOOTH v1.3
  491.  
  492. * Added the -x switch to allow the user to "turn-off" the surface
  493.   normal smoothing if desired.
  494.  
  495. Changes in SMOOTH v1.2
  496.  
  497. * Added the -a switch to allow the user to enter the aspect ratio of
  498.   their display device.
  499.  
  500. * Added the -b switch to create a bounding box for the triangle data.
  501.  
  502. Changes in SMOOTH v1.1
  503.  
  504. * Changed the output files to include decimal data to six places.  On
  505.   some RAW files with decimal data to six places and very small
  506.   triangles, 'rounding-off' to four decimal places caused "degenerate
  507.   triangles" to be created.  I haven't seen any RAW files with more
  508.   than six decimal places, so this should take care of the problem.
  509.  
  510. * Changed the code to close any open files more effectively.  In
  511.   certain rare cases an aborted (ctrl-C) file or an error termination
  512.   would create an invalid file in the FAT table.  This caused no real
  513.   harm other than it was almost impossible to delete the bad file.
  514.  
  515. * Added the -f switch to enter the Field of View Angle for the camera
  516.   position routine.
  517.  
  518. * Dropped support for all formats except POV. Since I only work with
  519.   POV, the 'work-arounds' for the other types were becomming bigger
  520.   than the actual program.
  521.  
  522.